FormatX$ Functions Action Formats a numeric value. Syntax FormatI$ ( expression#, fmt$) FormatL$ ( expression#, fmt$) FormatS$ ( expression#, fmt$) FormatD$ ( expression#, fmt$) FormatC$ ( expression#, fmt$) Remarks The Format X $ functions return a string that contains the formatted expression. The functions use the following arguments. ----------------------------------------------------------------------------- Argument Description ---------------------------------------------------------------------------- Argument Description ---------------------------------------------------------------------------- expression# A numeric expression to be formatted. fmt$ A string expression comprising BASIC display-format characters that detail how the expression is to be displayed. There are five separate add-on-library functions, depending on the data type of expression#. Use the appropriate function as shown below. ----------------------------------------------------------------------------- Function Data type of expression ---------------------------------------------------------------------------- FormatI$ Integer FormatL$ Long integer Function Data type of expression ---------------------------------------------------------------------------- FormatL$ Long integer FormatS$ Single precision FormatD$ Double precision FormatC$ Currency If fmt$ is a null string, BASIC uses the general format (which gives output identical to output with no formatting). To use the Format X $ functions in the QBX environment, use the DTFMTER.QLB Quick library. To use the Format X $ functions outside of the QBX environment, link your program with the appropriate DTFMT xx.LIB file. Depending on the compiler options you chose when you installed BASIC, one or more of the following files will be available. ----------------------------------------------------------------------------- Filename Compiler options Filename Compiler options ---------------------------------------------------------------------------- DTFMTER.LIB 80x87 or emulator math; DOS or OS-2 real mode DTFMTAR.LIB Alternate math; DOS or OS-2 real mode DTFMTEP.LIB 80x87 or emulator math; OS-2 protected mode DTFMTAP.LIB Alternate math; OS-2 protected mode The FORMAT.BI header file contains the necessary function declarations for using the Format X $ functions. For more information on using libraries, see Chapter 18, "Using LINK and LIB" and Chapter 19, "Creating and Using Quick Libraries" in the Programmer's Guide. Available Formats The Format X $ functions provide a wide range of formats for numeric and date-time data. The following symbols are used to create the formats. ----------------------------------------------------------------------------- Symbol Meaning ---------------------------------------------------------------------------- Null string Display the number in general format. 0 Digit placeholder. If the number has fewer digits on either side of the decimal point than there are zeros on either side of the decimal point in the format, the extra zeros are displayed. If the number has more digits to the right of the decimal point than there are zeros to the right in the format, the number is rounded to as many decimal places as there are zeros to the right. If the number has more digits to Symbol Meaning ---------------------------------------------------------------------------- If the number has more digits to the left of the decimal point than there are zeros to the left in the format, the extra digits are displayed. # Digit placeholder. Follows the same rules as for the 0 digit placeholder, except that extra zeros are not displayed if the number has fewer digits on either side of the decimal point than there are number signs (#) on either side of the decimal point. . Decimal point. This symbol determines how many Symbol Meaning ---------------------------------------------------------------------------- This symbol determines how many digits BASIC displays to the right and left of the decimal point. Depending on the country code set using the SetFormatCC routine, BASIC may use the comma as the decimal point. If the format contains only number signs (#) to the left of this symbol, numbers smaller than 1 are begun with a decimal point. To avoid this, you should use 0 as the first digit placeholder to the left of a decimal point instead of #. % Percentage. The expression is multiplied by 100 and the percent character (%) Symbol Meaning ---------------------------------------------------------------------------- 100 and the percent character (%) is inserted. ----------------------------------------------------------------------------- ---------------------------------------------------------------------------- , Thousands separator. BASIC separates thousands by commas (or by periods, depending on the country code set using the SetFormatCC routine) if the format contains a comma surrounded by digit placeholders (0 or #). Two adjacent commas, or a comma ---------------------------------------------------------------------------- adjacent commas, or a comma immediately to the left of the decimal point location (whether there is a decimal specified or not) means "Omit the three digits that fall between these commas, or between the comma and the decimal point, rounding as needed." E- E+ e- e+ Scientific format. If a format contains one digit placeholder (0 or #) to the right of an E-, E+, e-, or e+, BASIC displays the number in scientific format and inserts an E or e. The number of digit placeholders to the right determines the number of digits in the exponent. Use E- or e- to place a minus sign next to ---------------------------------------------------------------------------- e- to place a minus sign next to negative exponents. Use E+ or e+ to place a minus sign next to negative exponents and a plus sign next to positive exponents. . - + $ ( ) Space Display that literal character. To display characters other than one of these, precede each character with a backslash( \ ) or enclose the character(s) in double quotation marks (""). \ Display the next character in the format string. Many characters in the format string have a special meaning and cannot be displayed as literal ---------------------------------------------------------------------------- cannot be displayed as literal characters unless they are preceded by a backslash. The backslash is not displayed. This is the same as enclosing the next character in double quotation marks. Examples of such characters are the date- and time-formatting characters (y, m, d, h, s, a, and p) and the numeric-formatting characters (#, 0, %, E, e, comma, and period). " abc" Display whatever text is inside the double quotation marks. To include a text string in fmt$, you must use CHR$(34) to enclose ---------------------------------------------------------------------------- you must use CHR$(34) to enclose the text (34 is the ASCII code for double quotation mark). The Format X $ functions have the following general syntax. Format X $ ( expression#, fmt$). Some sample numeric formats are shown below for different values of fmt $ and expression#. (These examples all assume the country code is set to 1, United States.) The following example has two sections. the first section defines the format for positive numbers and zeros; the second section defines the format for negative numbers. $#,##0;($#,##0) You can use from one to three sections. ----------------------------------------------------------------------------- ---------------------------------------------------------------------------- One section only The format applies to all numbers. Two sections The first section applies to positive numbers and zeros; the second to negative numbers. Three sections The first section applies to positive numbers, the second to negative numbers, and the third to zeros. If you have semicolons with nothing between them, the missing section is printed using the format of the positive value. For example, the following format will display positive and negative numbers using the format in the first section, and "Zero" if the value is zero. "$#,##0;;Z\ero" Date-Time Formats Date-time serial numbers can be formatted with date-time or numeric formats (since date-time serial numbers are stored as floating-point values). Date-time formats have the following meanings. ----------------------------------------------------------------------------- Symbol Meaning ---------------------------------------------------------------------------- d dd ddd dddd Display the day as a number without leading zeros (1-12), as a number with leading zeros (01-12), as an abbreviation (Sun-Sat), or as a full name (Sunday-Saturday). m mm mmm mmmm Display the month as a number Symbol Meaning ---------------------------------------------------------------------------- m mm mmm mmmm Display the month as a number without leading zeros (1-12), as a number with leading zeros (01-12), as an abbreviation (Jan-Dec), or as a full month name (January-December). If you use m or mm immediately after the h or hh symbol, the minute rather than the month is displayed. yy yyyy Display the year as a two-digit number (00 - 99), or as a four-digit number (1900 - 2040). h hh Display the hour as a number without leading zeros (0 - 23), or as a number with leading zeros (00 - 23). If the format contains an AM or PM, the hour is based on the Symbol Meaning ---------------------------------------------------------------------------- AM or PM, the hour is based on the 12-hour clock. Otherwise, the hour is based on the 24-hour clock. m mm Display the minute as a number without leading zeros (0 - 59), or as a number with leading zeros (00 - 59). The m or mm must appear after an h or hh, or the month is displayed rather than the minute. s ss Display the second as a number without leading zeros (0 - 59), or as a number with leading zeros (00 - 59).. AM - PM am - pm A - P a - p Display the hour using the 12-hour clock. AM, am, A, or a is displayed with any time before Symbol Meaning ---------------------------------------------------------------------------- displayed with any time before noon. PM, pm, P, or p is displayed with any time between noon and 11.59 P.M. The following are examples of date and time formats. d-mmmm-yy 7-December-58 d-mmmm 7-December mmmm-yy December-58 h.mm AM-PM 8.50 PM h.mm.ss AM-PM 8.50.35 PM h.mm 20.50 h.mm.ss 20.50.35 m-d-yy h.mm 12-7-58 20.50 See Also PRINT, PRINT USING, STR$